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1. THE COMMAND SHELL 

1.1 INTRODUCTION 

COMMAND is a shell (or Command Line Interpreter) written lor the Atari ST 
computers. Typically it is used with ail the utilities and compilers in a development system 
to bypass the niceties of the windowing system. There are also many excellent shells 
written lor the Atari available through dealers or the Public Domain which can emulate 
your favorite CL1. 

1.2 COMMANDS 

DIR or LS [filenm.ext] [/I] [Id] [/t] 

• /I - anything but directories. 

• Id - directories only. 

• /t - terse: names only. 


PATH (;Ipathnm]...l 

• With path name sets default path lor batch and commands. 

• Without path name displays current path 


CAT or TYPE filenm.ext 

Writes filenm.ext to standard output. 


REM or ECHO [“string”] 

Strips quotes and writes string to standard output. 


CD [pathnm] 

• With pathnm it sets default for working directory 

• Without pathnm displays current working directory. 


MD [subdirectory name] 

Creates a new subdirectory in current directory. 


RD [pathnm] 

Removes named directory. 
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RM or DEL or ERA filenm 

Removes named file from directory. 


REN sourceJile_nm [destination_file_nm] 
Renames source to destination. 


SHOW [drive_spec:] 

Displays disk status for default drive or drive specified. 


INIT [drive_spec:] 

Reinitializes FAT entries thus wiping disk 


COPY sourcejile [destinationjile] 
Copies source to destination. 


MOVE sourcejile [destinationjitel 

Copies source to destination and deletes source. 


PAUSE 

Writes 'CR to continue...' to standard output and waits for a carriage return 
from standard input. 


EXIT 

Exits CLI to invoking program. 


VERSION 

Displays current version of OS. 


WRAP 

Enables line wrap. 


NOWRAP 

Disables line wrap. 


CLS 

Clears the screen. 


HELP 

This list of commands. 
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2.1 AS68 ASSEMBLER OPERATION 


The GEM DOS Assembler, AS68, assembles an assembly language source 
program for execution on the 68000 microprocessor. It produces a relocatable object 
file and, optionally, a listing. You can find a summary of the AS68 instruction set at 
the end of this section. Exceptions and additions to the standard Motorola instruction 
set appear in sections 2.6 and 2.7. 

2.2 INITIALIZING AS68 

If the file AS68SYM.DAT is not on your disk, you must create this file to 
initialize AS68 before you can use AS68 to assemble files. To initialize AS68, 
specify the AS68 command, the -I option, and the filename AS68INIT as shown 
below. 


{a}AS68 -I AS68INIT 

AS68 creates the output file AS68SYMB.DAT. which AS68 requires when it 
assembles programs. After you create this file, you need not specify this command 
line again unless you reconfigure your system to have different TPA boundaries. 

2.3 INVOKING THE ASSEMBLER (AS68) 

Invoke AS68 by entering a command with the following form: 

AS68 [-F pathname] [-P] OS pathname] [-U] [-L] [-N] [-1] 

[-0 object filename] source pathname £> listing pathname] 

Table 2-1 lists and describes the AS68 command line options. 


Table 2-1. Assembler Options 

Option Meaning 
-F pathname 

Specifies the directory in which the temporary files are created. If this option 
is not specified, AS68 creates the temporary files in the current default directory 

-I 

Initializes the assembler. See Section 2.2 for details. 
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-P 


If specificed, AS68 produces and prints a listing on the standard output device, 
which, by default, is the console. Redirect the listing, including error messages, to a 
file with the listing filename parameter. Note that error messages are produced 
whether or not the -P option is specified. No listing is produced, however, unless you 
specify the -P option. 

-S pathname 

Indicates the directory that contains the assembler initialization file, 
AS68SYMB.DAT. This file is created when you initialize AS68. AS68 reads the file 
AS68SYMB.DAT before it assembles a source file. If you do not specify this option, 
AS68 assumes the initi? ,: zation file is located in the current default directory. 

-U 


Causes all undefined symbols in the assembly to be treated as global 
references. 

-L 


Ensures all address constants are generated as longwords. Use the -L option 
for programs that require more than 64K for execution or if the TP A. is not contained 
in the first 64K bytes of memory. If -L is not specified, the program is assembled to 
run in the first 64K bytes of memory. If an address in the assembly does not fit within 
one word, an error occurs. 

-N 


Disables optimization of branches on forward references. Normally, AS68 
uses the 2-byte form of the conditional branch and the 4-byte BSR instruction 
wherever possible (instead of the 6-byte JSR instruction) to speed program execution 
and reduce instruction size. 

-T 


Enables AS68 to accept the 68010 microprocessor opcodes, 
source filename 

Specifies the file to assemble; you must supply this parameter. 

> listing filename 

Sends a program listing to the standard output device. Use the greater-than 
symbol, >, to direct the listing to a disk file. The listing includes assembler error 
messages. Note that if you do not specify -P with a listing filename, only the error 
messages are redirected to the iisting file. 
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2.4 ASSEMBLY LANGUAGE DIRECTIVES 

fable 2-2 lists the AS68 directives. 


Table 2-2. AS68 Directives 


Directive Meaning 
.comm label, expression 

The comm (common) directive specifies a label and the size of a common area 
that programs assembled separately can share. The largest common area of a 
group with the same label determines the final size of the program common area. 

data 


The data directive instructs AS68 to change the assembler base segment to 
the data segment. 

.bss 


The bss (block storage segment) directive instructs AS68 to change the 
assembler base segment to the block storage segment. You cannot assemble 
instructions and data in the bss. However, you can define symbols and reserve 
storage in the bss with the ds directive. 

.dc operandLoperand....] 

The dc (define constant) directive defines one or more constants tn memory. 
The operands can be symbols or expressions assigned numeric values by AS68, or 
explicit numeric constants in decimal or hexadecimal, or strings of ASCII characters. 
You must separate operands with commas. You must enclose string constants in 
single quotation marks. Each ASCII character is assigned a full byte of memory. The 
eighth bit is always 0. 

You can specify the length of each constant with a single letter parameter (byte 
= b, word = w, longword = I). You must separate the letter from the dc with a period 
as shown in the following explanations. 

.dc.b 


The constants are byte constants. If you specify an odd number of bytes, 
AS68 fills the odd byte on the right with zeros unless the next statement is another 
dc.b directive. When the next statement is a dc.b directive, the dc.b uses the odd 
byte. Byte constants are not relocatable. 
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dc.w 


The constants are word constants. If you specify an odd number of bytes, 
AS68 fills the last word on the right with zeros to force an even byte count. The only 
way to specify an odd number of bytes is with an ASCII constant. Word constants 
can be relocated 

dcJ 


The constants are longword constants. If less than a multiple of four bytes is 
entered, AS68 fills the last longword on the right with zeros to force a multiple of four 
bytes. Longword constants can be relocated. 

.ds operand 

The define storage directive (ds) reserves memory locations. The contents ot 
the memory that it reserves is not initialized. The operand specifies the number of 
bytes, words, or longwords that this directive reserves. The notation for these size 
specifications is shown below. 

.ds.b reserves memory locations in bytes 

.ds.w reserves memory locations in words 

.ds.l reserves memory locations in longwords 

.end 

The end directive informs AS68 that no more source code follows this 
directive. Code, comments, or multiple carriage returns cannot follow this directive. 

endc 

The endc directive denotes the end of the code that is conditionally assembled. 
It is used with other directives that conditionally assemble code. 

.equ (or =) expression 

The equate directive (equ or =) assigns the value of the expression in the 
operand field to the symbol in the label field that precedes the directive. The syntax 
for the equate directive are: 

label equ expression 
label = expression 

The label and operand fields are required. The label must be unique; it cannot 
be defined anywhere else in the program. The expression cannot include an 
undefined symbol or one that is defined following the expression. Forward 
references to symbols are not allowed for this directive 
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even 


The even directive increments the location counter to force an even boundary. 
For example, if specified when the location counter is odd, the location counter is 
incremented by one so that the next instruction or data field begins on an even 
boundary in memory. 

.giobi labell, label... j 
xdef labell, label...] 

.xref labell, label...] 

These directives make the label(s) external. If the labels are defined in the 
current assembly, this statement makes them available to other routines during a 
load by ALN. If the labels are not defined in the current assembly, they become 
unresolved external ref^-ences, which ALN links to external values with the same 
label in other routines. If you specify the -u option, the assembler makes all 
undefined labels external. 

.ifeq expression .ifne expression 

.ille expression Jilt expression 

Jfge expression Jfgt expression 

These directives test an expression against zero for a specified condition. If 
the expression is true, the code following is assembled; if false, the code is ignored 
until an end conditional directive (endc) is found. The directives and the conditions 
they test are: 


ifeq 

equal to zero 

ifle 

less than or equal to zero 

iflt 

less than zero 

ifne 

not equal to zero 

ifgt 

greater than zero 

ifge 

greater or equal to zero 


.ifc string 1’, string2' 

Jfnc string 1', ’string2’ 

The conditional string directive compares two strings. The c condition is true 
if the strings are exactly the same. The 'nc' condition is true if they do not match. 

.offset expression 

The offset directive creates a dummy storage section by defining a table of 
offsets with the define storage directive (ds). The storage definitions are not passed 
to the linker. The offset table begins at the address specified in the expression. 
Symbols defined in the offset table are internally maintained. No instructions or 
code-generating directives, except the equate (equ) and register mask (reg) 
directives, can be used in the table. The offset directive is terminated by one of the 
following directives: 
bss 
data 
end 
section 
text 
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.org expression 

The absolute origin directive (org) sets the location counter to the value ot the 
expression. Subsequent statements are assigned absolute memory locations with 
the new value of the location counter. The expression cannot contain any forward, 
undefined, or external references. 

page 


The page directive causes a page break which forces text to print on the top of 
the next page. It does not require an operand or a label and it does not generate 
machine code. 

The page directive allows you to set the page length for a listing of code. If 
you use this directive anrt print the source code by specifying the -P option in the 
AS68 command line, pages break at predefined rather than random places. The 
page directive does not appear on the printed program listing. 

.reg reglist 


The register mask directive builds a register mask that can be used by a 
movem instruction. (See Table 1-1.) .One or more registers can be listed in 
ascending order in the format: 

R?l-R[/R?[-R?...]...J] 

Replace the R in the above format with a register reference. Any of the following 
mnemonics are valid: 

A0-A7 • 

D0-D7 

R0-R15 

The following example illustrates a sample register list. 

A2-A4/A7/D1/D3-D5 

You can also use commas to separate registers as follows: 

A1.A2.D5.D7 


section # 

The section directive defines a base segment. The sections can be numbered 
from 0 to 15 inclusive. Section 14 always maps to data. Section 15 is bss. All other 
section numbers denote text sections. 

text 

The text directive instructs AS68 to change the assembler base segment to the 
text segment. Each assembly of a program begins with the first word in the text 
segment 
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2.5 SAMPLE COMMANDS INVOKING AS68 

{a}as68 -u -1 test.s 

This command assembles the source file TEST.S and produces the object file 
TEST.O. Error messages appear on the screen. Any undefined symbols are treated 
as global. 

{a}as68 -p smpl.s > smpl.l 

This command assembles the source file SMPL.S and produces the object file 
SMPL.O. The program must run in the first 64K of memory; that is, no address can 
be larger than 16 bits. Error messages and the listing are directed to the file SMPL.L. 

2.6 ASSEMBLY LANGUAGE DIFFERENCES 

The syntax differences between the AS68 assembly language and Motorola's 
assembly language are described in the following list. 

• In AS68, all assembler directives are optionally preceded by a period (.). For 
example, 

.equ or equ 
ds or ds 

• AS68 does not support, but accepts and ignores the following Motorola directives: 

comline 
mask 2 
idnt 
opt 

• The Motorola .set directive is implemented as the equate directive (equ). 

• AS68 accepts upper- and lowercase characters. You can specify instructions and 
directives in either case. However, labels and variables are case-sensitive. For 
example, the label START and Start are not equivalent. 

• For AS68, all labels must terminate with a colon (:). For example. 

A; FOO: 

However, if a label begins in column 1, it need not terminate with a colon. If a label is 
placed as the last statement of your assembly, it must generate code, ie. conditional 
statements may cause problems but a no op (nop) will be OK. 

• For AS68, ASCII string constants can be enclosed in either single or double 
quotes. For example, 

ABCD’ "ac14" 
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• For AS68, registers can be referenced with the following mnemonics: 

rO-r 1 5 

R0-R15 

d0-d7 

D0-D7 

a0-a7 

A0-A7 

Upper- and lowercase references are equivalent. Registers R0-R7 are the same as 
D0-D7 and R8-R15 are the same as A0-A7. 

• Use caution when manipulating the location counter forward in AS68. An 
expression can move the counter forward only. The unused space is filled with zeros 
in the text or data segments. 

• For AS68, comment lines can begin with an asterisk followed by an equals sign (* 
=), but only if one or more spaces exist between the asterisk and the equals sign as 
follows: 

* = This command loads R1 with zeros. 

* = Branch to subroutine XYZ. 

Be sure to include a space after the asterisk, as the location counter is 
manipulated with a statement of the form: 

*=expr 

• For AS68, the syntax for short form branches is bxx.b rather than bxx.s 

• The Motorola assembler supports a programming model in which a program 
consists of a maximum of 16 separately relocatable sections and an optional 
absolute section. The AS68 distributed with GEMDOS does not support this model. 
Instead, AS68 supports a model in which a program contains three segments, text, 
data, and bss as described in the Atari GEMDOS manual. 

2.7 ASSEMBLY LANGUAGE EXTENSIONS 

The following enhancements have been added to AS68 to make the assembly 
language more efficient: 

• When the instructions add. sub. and cmp are used with an address register in the 
source or destination, they generate adda, suba, and cmpa. When the clr instruction 
is used with an address register (Ax), it generates sub Ax, Ax. 

• add, and, cmp, eor, or, sub are allowed with immediate first operands and 
generate addi, andi, cmpi, eori, ori, and subi instructions if the second operand is not 
register-direct. 
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• All branch instructions generate short relative branches where Dossible. including 
forward references. 

• Any shift instruction with no shift count specified assumes a shift count of one 
For example, asl rt is equivalent to asl *1 ,rl. 

• A isr instruction is changed to a bsr instruction if the resulting bsr instruction is 
shorter than the jsr instruction. 

• The .text directive causes the assembler to begin assembling instructions in the 
text segment. The .data directive causes the assembler to begin assembling 
initialized data in the data segment. 

• The .bss directive instructs the assembler to begin defining storage in the bss. No 
instructions or constants nan be placed in the bss because the bss is for uninitialized 
data only. However, the .ds directives can be used to define storage locations, and 
the location counter (*) can be incremented. 

• The .globl directive in the form: 

globl labeil, label) ... 

makes the labels external. If they are . otherwise defined (by assignment or 
appearance as a label), they act within the assembly exactly as if the .globl directive 
were not given. However, when linking this program with other programs, these 
symbols are available to other programs. Conversely, if the given symbols are not 
defined within the current assembly, the linker can combine the output of this 
assembly with that of others which define the symbols. 

• The common directive (comm) defines a common region, which can be accessed 
by programs that are assembled separately. The syntax for the common directive is: 

comm label, expression 

The expression specifies the number of bytes allocated in the common region. If 
several programs specify the same label for a common region, the size of the region 
is determined by the value of the largest expression. 

The common directive assumes the label is an undefined external symbol in the 
current assembly. 

• The .even directive causes the location counter (*). if positioned at an odd 
address, to be advanced by one byte so the next statement is assembled at an even 
address. 

• The instructions move, add, and sub, specified with an immediate first operand 
and a data (D) register as the destination, generate Quick instructions, where 
possible. 
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2.8. AS68 ERROR MESSAGES 

The GEM DOS assembler, AS68, returns both nonfatal, diagnostic error 
messages and fatal error messages. Fatal errors stop the assembly of your program. 
There are two types of fatal errors: user-recoverable fatal errors and fatal errors in 
the internal logic of AS68. 

2.8.1. AS68 Diagnostic Error Messages 

Diagnostic messages report errors in the syntax and context of the program 
being assembled without interrupting assembly. Refer to the Motorola 16-Bit 
Microprocessor User’s Manual for a full discussion of the assembly language syntax. 

Diagnostic error messages appear in the following format: 

& line no. error message text 

The ampersand (&) indicates that the message comes from AS68. The line 
no. indicates the line in the source code where the error occurred. The error message 
text describes the error. Diagnostic error messages appear at the console after 
assembly, followed by a message indicating the total number of errors. In a print-out, 
they print on the line preceding the error. Table A-1 lists the AS68 diagnostic error 
messages in alphabetical order. 

Table 2-3. AS68 Diagnostic Error Messages 

Message Meaning 

&. line no. backward assignment to * 

The assignment statement in the line indicated illegally assigns the location 
counter (*) backward. Change the location counter to a forward assignment and 
reassemble the source file. 

&. line no. bad use of symbol 

A symbol in the source line indicated has been defined as both global and 
common. A symbol can be either global or common, but not both. Delete one of the 
directives and reassemble the source file. 

&. line no. constant required 

An expression on the line indicated requires a constant. Supply a constant 
and reassemble the source file. 
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&. line no. end statement not at end of source 

The end statement must be at the end of the source code. The end statement 
cannot be followed by a comment or more than one carriage return. Place the end 
statement at the end of the source code, followed only by a single carriage return 
and reassemble the source file. 

& line no. illegal addressing mode 

The instruction on the line indicated has an invalid addressing mode. Provide a 
valid addressing mode and reassemble the source file. 

&. line no. illegal constant 

The line indicated contains an illegal constant. Supply a valid constant and 
reassemble the source file. 

&. line no. illegal expr 

The line indicated contains an illegal expression. Correct the expression and 
reassemble the source file. 

&. line no. illegal external 

The line indicated illegally contains an external reference to an 8-bit quantity. 
Rewrite the source code to define the reference locally or use a 16-bit reference and 
reassemble the source file. 

&. line no. illegal format 

An expression or instruction in the line indicated is illegally formatted. Examine 
the line. Reformat where necessary and reassemble the source file. 

&. line no. illegal index register 

The line indicated contains an invalid index register. Supply a valid register and 
reassemble the source file. 

& line no. illegal relative address 

An addressing mode specified is not valid for the instruction in the line 
indicated. Refer to the Motorola 16-Bit Microprocessor User’s Manual for valid 
register modes for the specified instruction. Rewrite the source code to use a valid 
mode and reassemble the file. 

&. line no. illegal shift count 

The instruction in the line indicated shifts a quantity more than 31 times. Modify 
the source code to correct the error and reassemble the source file. 
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& line no. illegal size 

The instruction in the line indicated requires one of the following three size 
specifications: b (byte), w (word), or I (longword). Supply the correct size specification 
and reassemble the source file. 

&. line no. illegal string 

The line indicated contains an illegal string. Examine the line. Correct the string 
and reassemble the source file. 

& line no. illegal text delimiter 

The text delimiter in the line indicated is in the wrong format. Use single 
quotes ('text') or double quotes ("text") to delimit the text and reassemble the source 
file. 

& line no. illegal 8-bit displacement 

The line indicated illegally contains a displacement larger than 8-bits. Modify 
the code and reassemble the source file. 

& line no. illegal 8-bit immediate 

The line indicated illegally contains an immediate operand larger than 8-bits. 
Use the 16- or 32-bit form of the instruction and reassemble the source file. 

&. line no. illegal 16-bit displacement 

The line indicated illegally contains a displacement larger than 16-bits. Modify 
the code and reassemble the source file. 

&. line no. illegal 16-bit immediate 

The line indicated illegally contains an immediate operand larger than 16-bits. 
Use the 32-bit form of the instruction and reassemble the source file. 

& line no. invalid data list 

One or more entries in the data list in the line indicated is invalid. Examine the 
line for the invalid entry. Replace it with a valid entry and reassemble the source file. 

&. line no. invalid first operand 

The first operand in an expression in the line indicated is invalid. Supply a 
valid operand and reassemble the source file. 
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&. line no. invalid instruction length 

The instruction in the line indicated requires one of the following three size 
specifications: b (byte), w (word), or I (longword). Supply the correct size 
specification and reassemble the source file. 

& line no. invalid label 

A required operand is not present in the line indicated, or a iabel reference in 
the line is not in the correct format. Supply a valid label and reassemble the source 
file. 

& line no. invalid opcode 

The opcode in the line indicated is non-existent or invalid. Supply a valid 
opcode and reassemble the source file. 

& line no. invalid second operand 

The second operand in an expression in the line indicated is invalid. Supply a 
valid operand and reassemble the source file. 

& line no. label redefined 

This message indicates that a label has been defined twice. The second 
definition occurs in the line indicated. Rewrite the source code to specify a unique 
label for each definition and reassemble the source file. 

&. line no. missing ) 

An expression in the line indicated is missing a right parenthesis. Supply the 
missing parenthesis and reassemble the source file. 

& line no. no label for operand 

An operand in the line indicated is missing a label. Supply a label and 
reassemble the source file. 

& line no. opcode redefined 

A label in the line indicated has the same mnemonics as a previously specified 
opcode. Respecify the label so that it does not have the same spelling as the 
mnemonic for the opcode. Reassemble the source file. 

&. line no. register required 

The instruction in the line indicated requires either a source or destination 
register. Supply the appropriate register and reassemble the source file. 
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&. line no. relocation error 

An expression in the line indicated contains more than one externally defined 
global symbol. Rewrite the source code. Either make one of the externally defined 
global symbols a local symbol, or evaluate the expression within the code. 
Reassemble the source file. 

& line no. symbol required 

A statement in the line indicated requires a symbol. Supply a valid symbol and 
reassemble the source file. 

& line no. undefined symbol in equate 

One of the symbols in the equate directive in the line indicated is undefined. 
Define the symbol and reassemble the source file. 

&. line no. undefined symbol 

The line indicated contains an undefined symbol that has not been declared 
global. Either define the symbol within the module or define it as a global symbol and 
reassemble the source file. 

2.8.2. User-recoverable Fatal Error Messages 

Table A-2 describes fatal error messages for AS68. When an error occurs because 
the disk is full, AS68 creates a partial file. Erase the partial file to ensure that you do 
not try to link it. 

Table 2-4. AS68 User-recoverable Fatal Error Messages 

&. cannot create init: AS68SYMB.DAT 

AS68 cannot create the initialization file because the path name is incorrect or 
the disk to which it was writing the file is full. If you used the -S switch to redirect the 
symbol table to another disk, check the path name. If it is correct, the disk is full. 
Erase unnecessary files, if any, or insert a new disk before you reinitialize AS68. 
Erase the partial file that was created on the full disk to ensure that you do not try to 
link it. 

&. expr opstk overflow 

An expression in the line indicated contains too many operations for the 
operations stack. Simplify the expression before you reassemble the source code. 

&. expr tree overflow 

The expression tree does not have space for the number of terms in one of the 
expressions in the indicated line of source code. Rewrite the expression to use fewer 
terms before you reassemble the source file. 
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&. I/O error on loader output file 

The disk to which AS68 was writing the loader output file is full. AS68 wrote a 
partial file. Erase unnecessary files, if any, or insert a new disk and reassemble the 
source file. Erase the partial file that was created on the full disk to ensure that you 
do not try to link it. 

&. I/O write error on it file 

The disk to which AS68 was writing the intermediate text file is full. AS68 wrote 
a partial file. Erase unnecessary files, if any, or insert a new disk and reassemble the 
source file. Erase the partial file that was created on the full disk to ensure that you 
do not try to link it. 

&. it read error itoffset= "o. 

The disk to which AS68 was writing the intermediate text file is full. AS68 
wrote a partial file. The variable itoffset= no. indicates the first zero-relative byte 
number not read. Erase unnecessary files, if any, or insert a new disk and 
reassemble the source file. Erase the partial file that was created on the full disk to 
ensure that you do not try to link it. 

&. Object file write error 

The disk to which AS68 was writing the object file is full. AS68 wrote a partial 
file. Erase unnecessary files, if any, or insert a new disk and reassemble the source 
file. Erase the partial file that was created on the full disk to ensure that you do not try 
to link it. 

& overflow of external table 

The source code uses too many externally defined global symbols for the size 
of the external symbol table. Eliminate some externally defined global symbols and 
reassemble the source file. 

& Read Error On Intermediate File: ASXXXXn 

The disk to which AS68 was writing the intermediate text file ASXXXX is full. 
AS68 wrote a partial file. The variable n indicates the drive on which ASXXXX is 
located. Erase unnecessary files, if any, or insert a new disk and reassemble the 
source file. Erase the partial file that was created on the full disk to ensure that you 
do not try to link it. 

& symbol table overflow 

The program uses too many symbols for the symbol table. Eliminate some 
symbols before you reassemble the source code. 
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&. Unable to open file filename 

The source filename indicated by the variable filename is invalid or has an 
invalid path name. Check the path name and the filename. Respecify the command 
line before you reassemble the source file. 

&. Unable to open input file 

The filename in the command line indicated does not exist or has an invalid 
path name. Check the path name and the filename. Respecify the command line 
before you reassemble the source file. 

&. Unable to open temporary file 

You used an invaM path name or the disk to which AS68 was writing is full. 
Check the path name, if it is correct, the disk is full. Erase unnecessary files, if any, 
or insert a new disk before you reassemble the source file. 

& Unable to read init file: AS68SYMB.DAT 

The path name used to specify the initialization file is invalid or the assembler 
has not been initialized. Check the path name. Respecify the command line before 
you reassemble the source file. If the assembler has not been initialized, refer to 
Section 5 for instructions. 

&. Write error on init file: AS68SYMB.DAT 

The disk to which AS68 was writing the initialization file is full. AS68 wrote a 
partial file. Erase unnecessary files,' if any, or insert a new disk and reassemble the 
source file. Erase the partial file that was created on the full disk to ensure that you 
do not try to link it. 

& write error on it file 

The disk to which AS68 was writing the intermediate text is full. AS68 wrote a 
partial file. Erase unnecessary files, if any, or insert a new disk. Erase the partial file 
that was created on the full disk to ensure that you do not try to link it. Reassemble 
the source file. 

2.8.3. AS68 Internal Logic Error Messages 

The following are messages indicating fatal errors in the internal logic of AS68 

&. doitrd: buffer botch pitix=nnn itbuf=nnn end=nnn 

& doitwr: it buffer botch 

& invalid radix in oconst 

&. i.t. overflow 

&. it sync error itty=nnn 

& seek error on it fife 

& outword: bad rlflg 
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2.9 INSTRUCTION SET SUMMARY 

This section contains two tables that describe the assembler instruction set 
distributed with GEMDOS. Table 2-5 summarizes the assembler (AS68) instruction 
set. Table 2-6 lists variations on the instruction set listed in Table 2-5. For details on 
specific instructions, refer to Motorola’s 16-Bit Microprocessor User’s Manual, third 
edition, MC68000UM(AD3). 

Table 2-5. Instruction Set Summary 


Instruction 

Description 

abed 

Add Decimal with Extend 

add 

Add 

and 

Logical AND 

asl 

Arithmetic Shift Left 

asr 

Arithmetic Shift Right 

bcc 

Branch Conditionally 

bchg 

Bit Test and Change 

bclr 

Bit T est and Clear 

bra 

Branch Always 

bset 

Branch Test and Set 

bsr 

Branch to Subroutine 

btst 

Bit Test 

chk 

Check Register Against Bounds 

clr 

Clear Operand 

emp 

Compare 

dbcc 

Test Condition. Decrement, and Branch 

divs 

Signed Divide 

divu 

Unsigned Divide 

eor 

Exclusive OR 

exg 

Exchange Registers 

ext 

Sign Extend 

illegal 

Illegal Instruction 

jmp 

Jump 

jsr 

Jump to Subroutine 

lea 

Load Effective Address 

link 

Link Stack 

Isl 

Logical Shift Left 

Isr 

Logical Shift Right 
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move 

Move 

movem 

Move Multiple Registers 

movep 

Move Peripheral Data 

muls 

Signed Multiply 

mulu 

Unsigned Multiply 

nbcd 

Negate Decimal with Extend 

neg 

Negate 

nop 

No Operation 

no 

One s Complement 

or 

Logical OR 

pea 

Push Effective Address 

reset 

Reset External Devices 

rol 

Rotate Left without Extend 

ror 

Rotate Right without Extend 

roxl 

Rotate Left with Extend 

roxr 

Rotate Right with Extend 

rte 

Return From Exception 

rtr 

Return and Restore 

rts 

Return from Subroutine 

sbcd 

Subtract Decimal with Extend 

see 

Set Conditional 

stop 

Stop 

sub 

Subtract 

swap 

Swap Data Register Halves 

tas 

Test and Set Operand 

trap 

Trap 

trapv 

Trap on Overflow 

tst 

Test 

unik 

Unlink 
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Table 2-5. 

Variations of Instruction Types 

Instruction 

Variation 


add 

add 

Add 


adda 

Add Address 


addq 

Add Quick 


addi 

Add Immediate 


addx 

Add with Extend 

and 

and 

Logical AND 


andi 

AND Immediate 


andi 

to ccr 


andi 

to sr 

cmp 

cmp 

Compare 


cmpa 

Compare Address 


cmpm 

Compare Memory 


cmpi 

Compare Immediate 

eor 

eor 

Exclusive OR 


eori 

Exclusive OR Immediate 


eori to ccr 
eori to sr 


move 

move 

Move 


movea 

Move Address 


moveq 
move to ccr 
move to sr 

Move Quick 


move from sr 
move to usp 

neg 

neg 

Negate 


negx 

Negate with Extend 

or 

or 

Logical OR 


ori 

ori to ccr 

OR Immediate 


ori to sr 

OR Immediate to Status Register 

sub 

sub 

Subtract 


suba 

Subtract Address 


subi 

Subtract Immediate 


subq 

Subtract Quick 


subx 

Subtract with Extend 
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3.1 INTRODUCTION 

The Archive utility, AR68, creates a library or replaces, adds, deletes, lists, 01 
extracts object modules in an existing library. AR68 can be used on the C Run-time 
Library distributed with GEM DOS and documented in the GEM DOS Supplement to 
the C Language Programmer’s Guide for CP/M-68K. 

3.2 AR68 SYNTAX 

To invoke AR68, specify the components of the following command line 
Optional components are enclosed in square brackets ([]). 

AR68 DRTWX[AV][F pathname] [OPMOD] ARCHIVE OBMOD1 [0BM0D2...] [>filespec] 

You can specify multiple object modules in a command line provided the 
command line does not exceed 127 bytes. The delimiter character between 
components consists of one or more spaces. 

Table 3-1 lists and describes the components of the AR68 command line. 

Table 3-1. AR68 Command Line Components 


AR68 


Invokes the Archive utility. However, if you specify only the AR68 command 
AR68 returns the following command line syntax and system prompt. 

{a}ar68 

usage: AR68 DRTWX[AV][F pathname] [OPMOD] ARCHIVE OBMOD1[OBMOD2 . . . ] 

[>filespec] 

DRTWX 

Indicates you must specify one of these letters as an AR68 command. Each of 
these one-letter commands and its options are described in Section 3.4. 

AV 

Indicates you can specify one or both of these one-letter options. These 
options are described with the commands in Section 3.4. 

F pathname 

Specifies the path to the directory in which the temporary file created by AR68 
resides. If no path name is specified, the current default directory is used. AR68 
creates a temporary fiie called AR68.TMP that AR68 uses as a scratch pad area. 
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OPMOD 

Indicates an object module within the library that you specify. The OPMOD 
parameter indicates the position in which additional object modules reside when you 
incorporate modules in the library and specify the A option. 

ARCHIVE 

File specification of the library. 

OBMOD1 [OBMOD2 ...] 

Indicates one or more object modules in a library that AR68 deletes, adds, 
replaces, or extracts. 

>filespec 

Redirects the output to the file specification you specify, rather than sending 
the output to the standard output device, which is usually the console device 
(CONSOLE). You can redirect the output for any of the AR68 commands described 
in Section 3.4. 

3.3 AR68 OPERATION 


AR68 sequentially parses the command line once. AR68 searches for, inserts, 
replaces, or deletes object modules in the library in the sequence in which you 
specify them in the command line. Section 3 4 describes each of the commands 
AR68 supports. 

When AR68 processes a command, it creates a temporary file called 
AR68.TMP, which it uses as a scratch pad. After the operation is complete AR68 
erases AR68.TMP. However, AR68.TMP is not always erased if an error occurs. If 
this occurs, erase AR68.TMP with the ERA command and refer to Appendix D for 
error messages output by AR68 

3.4 AR68 COMMANDS AND OPTIONS 

This section describes AR68 commands and their options. Examples illustrate 
the effect and interaction between each command and the options it supports. 

3.4.1 The D Command 

The D command deletes from the library one or more object modules specified in the 
command. The D command supports the following option: 
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V 

Lists the modules in the library and indicates which modules are retained and 
deleted by the D command. The V option precedes modules retained in the library 
with the lowercase ietter c and modules deleted from the library with the lowercase 
letter d as follows: 

{a}ar68 dv myrah.arc orc.o 
c red.o 
c blue.o 
d orc.o 
c white. o 

The D command deletes the module ORC.O from the library MYRAH.ARC. In 
addition to listing the modules in the library, the V option indicates which modules are 
retained and deleted. 

3.4.2 The R Command 

The R command creates a library when the one specified in the command line 
does not exist, or replaces or adds object modules to an existing library. You must 
specify one or more object modules. 

You can replace more than one object module in the library by specifying the 
module names in the command line. However, when the library contains two or more 
modules with the same name, AR68 replaces only the first module it finds that 
matches the one specified in the command line. AR68 replaces modules already in 
the library only if you specify their names prior to the names of new modules to be 
added to the library. For example, if you specify the name of a module you want 
replaced after the name of a module you are adding to the library, AR68 adds both 
modules to the end of the library. 

By default, the R command adds new modules to the end of the library. The R 
command adds an object module to a library if: 

• The object module does not already exist in the library. 

• You specify the A option in the command line. 

• The name of the module follows the name of a module that does not 
already exist in the library. 

The A option indicates where AR68 adds modules to the library. You specify 
the relative position by including the OPMOD parameter with the A option. 

The R command also supports the V option, which lists the modules in the 
library and indicates the result of the operation performed on the library Both the A 
and V options are described below. 
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A 

The A option adds one or more object modules following the module specified 
in the command line: 

{a}ar68 rav sdav.o myrah.arc work.o mail.o 
c much.o 
c sdav.o 
a work.o 
a mai 1 . o 
c less.o 

The RAV command adds the object modules WORK.O and MAIL.O after the 
module SDAV.O in the library MYRAH.ARC. The V option, described below, lists all 
the modules in the library. New modules are preceded by the lowercase letter a and 
existing modules are preceded by the lowercase letter c. 

V 

The V option lists the object modules that the R command replaces or adds. 

{a}ar68 rv jnnk.man nail.o wrench. o 
c saw.o 
c ham.o 
r nail .o 
c screw. o 
a wrench. o 

The R command replaces the object module NAIL.O and adds the module 
WRENCH. O to the library JNNK.MAN. The V option lists object modules in the 
library and indicates which modules are replaced or added. Each object module that 
is replaced is preceded with the lowercase letter r and each one that is added is 
preceded with the lowercase letter a. 

3.4.3 The T Command 

The T command requests that AR68 print a table of contents or a list of 
specified modules in the library. The T command prints a table of contents of all 
modules in the library only when you do not specify names of object modules in the 
command line. It supports the following option. 

V 

The V option displays the size of each file in the table of contents as shown in 
the following example. 

{a}ar68 tv wine. bad 
rw-rw-rw- 0/0 6818 rose.o 

rw-rw-rw- 0/0 2348 white. o 

rw-rw-rw- 0/0 396 red.o 

The T command prints a table of contents in the library WINE. BAD. In addition to 
listing the modules in the library, the V option requests the size of each module. The 
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character string rw-rw-rw- 0/0 that precedes the module size is meaningless for GEM 
DOS. However, if the file is transferred to a UNIX... system, the character string 
denotes the file protection and file owner. The size specified by the decimal number 
that precedes the object module name indicates the number of bytes in the module. 

3.4.4 The W Command 

The W command writes a copy of an object module in the library to the 
>filespec parameter specified in the command line. This command allows you to 
extract a copy of a module from a library and rename the copy when you write it to 
another disk, as shown below. For this command, the >filespec parameter is 
required. 

{a}ar68 w go. arc now.o > b:\root\newd\file.o 

The W command writes a copy of the object module NOW.O from the library 
GO. ARC to the file FILE.O in the NEWD subdirectory on drive B. 

3.4.5 The X Command 

The X command extracts a copy of one or more object modules from a library 
and writes them to the default disk. If no object modules are specified in the 
command line, the X command extracts a copy of each module in the library. The X 
command supports the following option. 

V 

The V option lists only those modules the X command extracts from the library. 
It precedes each extracted module with the lowercase letter x as follows: 

{a}ar68 xv jnnk.man saw.o ham.o screw. o 
x saw.o 
x ham.o 
x screw. o 

3.5 AR68 ERRORS 

When AR68 incurs an error during an operation, the operation is not 
completed. The original library is not modified if the operation would have modified 
the library. Thus, no modules in the library are deleted, replaced, added, or extracted. 

When you specify the >filespec parameter in the command line to redirect the 
output and one or more errors occur, the error messages are sent to the output file. 
Thus, you cannot detect the errors without displaying or printing the file to which the 
output was sent. If the contents of the output file is an object file (see the W 
command), you must use the DUMP utility described in Section 4 to read any error 
messages. 

The GEM DOS Archive utility. AR68, returns two types of fatal error messages: 
diagnostic and logic. Both types of fatal error messages show at the console as they 
occur. 
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3.5.1. Fatal Diagnostic Error Messages 

Table 3-2 lists AR68 fatal error messages in alphabetical order with 
explanations and suggested user responses. 

Table 3-2. AR68 Fatal Diagnostic Error Messages 

filename not in archive tile 

The object module indicated by the variable filename is not in the library. 
Check the filename before you reenter the command line. 

cannot create filename 

The path name fc. the file indicated by the variable filename is invalid, or the 
disk to which AR68 is writing is full. Check the path name. If it is valid, the disk is full. 
Erase unnecessary files, if any. or insert a new disk before you reenter the command 
line. 

cannot open filename 

The file indicated by the variable filename cannot be opened because the 
filename or the path name is incorrect. Check the path name and the filename 
before you reenter the command line. 

invalid option flag: x 

The symbol, letter, or number in the command line indicated by the variable x 
is an invalid option. Refer Section 3 of this manual for an explanation of the AR68 
command line options. Specify a valid option and reenter the command line. 

not archive format: filename 

The file indicated by the variable filename is not a library. Ensure that you are 
using the correct filename before you reenter the command line. 

not object file: filename 

The file indicated by the variable filename is not an object file, and cannot be 
added to the library. Any tile added to the library must be an object file, output by the 
assembler, AS68, or the compiler. Assemble or compile the file before you reenter 
the AR68 command line. 

one and only one of DRTWX flags required 

The AR68 command line requires one of the D, R, T, W, or X commands, but 
not more than one. Reenter the command line with the correct command. Refer to 
Section 7 for an explanation of the AR68 commands. 


Page 6 


A TAP/ CORPORA T/ON 


Gem DOS Programmers' Too/s ~ AH68 


filename not in library 

The object module indicated by the variable filename is not in the library. 
Ensure that you are requesting the filename of an existing object module before you 
reenter the command line 

Read error on filename 

The file indicated by the variable filename cannot be read. This message 
means one of three things: the file listed at filename is corrupted; a hardware error 
has occurred; or when the file was created, it was not correctly written by AR68 due 
to an error in the internal logic of AR68. 

Cold start the system and retry the operation. If you receive this error message 
again, you must erase and recreate the file. Use your backup fife, if you maintained 
one. 

temp file write error 

The temporary file is full. Erase unnecessary files, if any, or insert a new disk before 
you reenter the command line. 

usage: AR68 DRTWX[AV][F D:] [OPMOD] ARCHIVE OBMOD1[OBMOD2 . . . ] [>fi 1 espec] 

This message indicates a syntax error in the command line. The correct format 
for the command line is given, with the possible ootions in brackets. 

Write error on filename 

The disk to which AR68 is writing the file indicated by the variable filename is 
full. Erase unnecessary files, if any, or insert a new disk before you reenter the 
command line. 

3.5.2. AR68 Internal Logic Error Messages 

The following are messages that indicate fatal errors in the internal logic of 

AR68: 


cannot reopen filename 

seek error on library 

Seek error on tempname 

Unable to recreate— library is in filename 

For the last error. Unable to recreate— library is in filename, you should rename 
the temporary file indicated by the variable filename. AR68 used the library to create 
the temporary file, then deleted the library in order to replace it with the updated 
temporary file. This error occurred because AR68 cannot write the temporary file 
back to the original location. The entire library is in the temporary file. 
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4.1 INTRODUCTION 

This section describes the DUMP and SIZE68 programming utilities. DUMP 
displays the contents offiles in hexadecimal and ASCII notation. SIZE68 displays the 
total size of a memory image command file and the size of each of its program 
segments. 

4.2 DUMP UTILITY 

The DUMP utility (DUMP) displays the contents of a GEM DOS file in both 
hexadecimal and ASCII notation You can use DUMP to display any GEM DOS file 
regardless of the format of its contents (binary data, ASCII text, an executable file). 

4.2.1 Invoking DUMP 

Invoke DUMP by entering a command with the following input components in 
the following format: 

DUMP [ -sxxxx ] fil enamel [ >filename2 ] 

Table 4-1 lists the DUMP command line components and their meanings. 

Table 4-1. DUMP Command Line Components 
Component Meaning 
-sxxxx 


xxxx is an optional offset (in hexadecimal) into the fiie. If specified. DUMP 
starts dumping the contents of the file from the byte-offset xxxx and continues until it 
displays the contents of the entire file. By default. DUMP starts dumping the contents 
of the file from the beginning of the file until it dumps the contents of the entire file. 

filename 1 

Name of the file you want to dump. 

>filename2 

The greater than sign (>) followed by a filename or logical device redirects the 
output of DUMP. You can specify any valid GEM DOS specification, or one of the 
logical device names, CON: (console) or LST: (list device). If you do not specify this 
optional parameter, DUMP sends its output to the console. 
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4.2.2 DUMP Output 

DUMP sends its output to the console (or to a tile or device, it specitied), 8 
words per line, in the following format: 

rrrr oo (ffffff): hhhh hhhh... hhhh *aaaaaaaaaaaaaaaa* 

The components of a DUMP command line are as follows: 

Component Meaning 

rrrr 

Record number (GEM DOS records are 128 bytes) of the current line of the 
display. 

00 

Offset (in hex bytes) from the beginning of the GEM DOS record. 


ffffff 

Offset (in hex bytes) from the beginning of the file 

hhhh 

Contents of the file displayed in hexadecimal, 
aaaaaaaa 

Contents of the file displayed as ASCII characters. If any character is not 
representable in ASCII, it is displayed as a period (.). 

4.2.3 DUMP Examples 

In the following example. DUMP is invoked to display the contents of a 
command file that contains data in both binary and ASCII form. 

{a}dump dump. 68k 

00 (000000): 601a 0000 

10 ( 000010 ) : 0000 0000 .... 

20 (000020): 5275 6e74 .... 

30 (000030): 7420 3139 

40 (000040): 6c20 5265 

50 (000050): 3320 206f 

.... (and so on) . . . 

4.3. DUMP ERROR MESSAGES 

DUMP returns fatal, diagnostic error messages at the console. Table 4- 
2 lists the DUMP error messages in alphabetical order with explanations and 
suggested user responses. 


oooo * 4 4 a. .* 

4320 * ' 4C * 


6768 ‘‘RuntimeCopyright* 
7461 *t 1982 by Digita* 
2c30 *1 Research V01.0* 
001c *3 o. ."h. .&ISh. 


Page 2 


A TAP/ COPPOPA T/ON 


Gem DOS Programmers ' Too/s - Utilities 


Table 4-2. DUMP Error Messages 


Message Meaning 
Unable to open filename 

Either the path name for the input file indicated by the variable filename is 
incorrect, or the filename is misspelled. Check the filename and path name before 
you reenter the DUMP command line. 

Usage: dump [-shhhhhh] file 

The command line syntax is incorrect. The correct syntax is given in the error 
message. Specify the DUMP command and the filename. If you want to display the 
contents of the file from a specific address in the file, specify the -S option followed 
by the address. Refer to Section 4.2 for discussion of the DUMP command line and 
options. 

4.4 SIZE68 UTILITY 

The SIZE68 utility (SIZE68) indicates if the program segments within one or 
more command files are contiguous or non-contiguous. displays the size of each 
program segment and the symbol table, and reports if the command files are 
relocatable or non-relocatable. SIZE68 displays both decimal and hexadecimal 
values for the sizes of the program segments and the symbol table. GEM DOS 
command files usually have a filetype of .PRG or .REL. The total size of a command 
file’s segments returned by SIZE68 and the size of a command file returned by the 
DIR command are not equal. The file size returned by SIZE68 includes the size of 
the text, data, and bss program segments and the size of the symbol table but does 
not include the size of the header and and relocation bits. For more details on the 
DIR command, refer to the GEM DOS User’s Guide. 
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4.4.1 Invoking SIZE68 

Invoke SIZE68 by entering a command line with the following tormat: 

SIZE68 filename [filename2 filename3, ... ] [ >outfile ] 

The SIZE68 command line components have the following meaning: 
Component Meaning 
filename 

File specification of a file whose size you want to determine. 
filename2 filename3 .... 

One or more additional file specifications of files whose sizes you want to 
determine. SIZE68 can process multiple files, provided the command line does not 
exceed 128 bytes. Note that SIZE68 also accepts wildcard file specifications. 

> outfile 

Specifies the file specification to which SIZE68 sends its output. If you do not 
specify an output file specification, SIZE68 sends the output to the console. For the 
output file specification, you can specify a valid GEM DOS filename, or one of the 
logical device names, CON:(console) or LST: (list device). 

4.4.2 S1ZE68 Examples and Output 

This section contains two examples that show SIZE68 command lines and 
output. 

1. The following SIZE68 command line example returns information about the 
program 

segments in one command file. 

{a}SIZE68 SIZE68 . PRC 
SIZE68.PRG: 

Contiguous 
.text length 
.data length 
.bss length 
Symbol table length 
Start of .text 
File is relocatable 

SIZE68.PRG contains a 9312-byte (decimal) text segment, a 1179-byte (decimal) 
data segment, and a 9140-byte (decimal) bss; the segments are contiguous and 
SIZE68 is relocatable. Hexadecimal notations for the decimal values are 
displayed in the last column of SIZE68 output. 


9312 2460 

1178 49A 

9140 23B4 

0 0 

0 0 
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2. The following SIZE68 command line uses a wildcard file specification to return 
information on an object file, a command file, and a text file. 


{a}SIZE68 

FIND.O: 


FIND.PRG: 


FILE. MSG: 


FI* . * 




Contiguous 

.text length 

= 

1072 

430 

.data length 

= 

188 

BC 

.bss length 

= 

0 

0 

Symbol table length 

= 

1708 

6AC 

Start of .text 
File is relocatable. 

= 

0 

0 


Contiguous 




.text length 

= 

9888 

26A0 

.data length 

= 

1060 

424 

.bss length 

= 

9396 

24B4 

Symbol table length 

= 

0 

0 

Start of .text 

= 

0 

0 

File is relocatable. 




Not a program file 





Notice that when you specify a file that is not a command file (FILE. MSG, 
an ASCII file, for example), SIZE68 displays: 


Not a program file. 

When you specify an absolute program file whose segments are non- 
contiguous in a SIZE68 command line, SIZE68 includes the following messages in its 
output: 


Non-contiguous 

No relocation information in file. 
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4 5. SIZE68 ERROR MESSAGES 

SIZE68 returns fatal, diagnostic error messages at the console. Table 4-3 lists 
the SIZE68 error messages in alphabetical order with explanations and suggested 
user responses. 


Table 4-3. SIZE68 Error Messages 


Message Meaning 
File format error: filename 

The file indicated by the variable filename is neither an object file nor a 
command file. SIZE68 requires either an object file, output by the assembler or the 
compiler, or a command file, output by the linker. Ensure that the file specified is one 
of these and reenter the SIZE68 command line. 

read error on filename 

The file indicated by the variable filename is truncated. Rebuild the file. 
Reassemble or recompile, then relink the source file before you' reenter the SIZE68 
command line. 

unable to open filename 

Either the path name is incorrect, or the file indicated by the variable filename 
does not exist. Check the path name and filename. Reenter the SIZE68 command 
line. 
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The Motorola S-record format is a method of representing binary memory 
images in an ASCII form. The primary use of S-records is to provide a convenient 
form for transporting programs between computers. Since most computers have a 
means of reading and writing ASCII information, the format is widely applicable. 

An S-record file consists of a sequence of S-records of various types. The 
entire content of an S-record is ASCII. When a hexadecimal number needs to be 
represented in an S-record, it is represented by the ASCII characters for the 
hexadecimal digits comprising the number. Each S-record contains the five fields 
shown in Figure A-l. Table A-l describes each field. 


Field ^ type length address data cksum 

Size in characters 1 1 2 2, 4 or 6 varies 2 


Figure A-l . S-record Format 

Table A-l. S-record Field Descriptions 


Field Description 
S 

The ASCII character S. This signals the beginning of the S-record. 

type 

A digit between 0 and 9, represented in ASCII, with the exceptions that 4 
and 6 are not allowed. The use of each type value is explained in Table A-2. 


length 

The number of character pairs in the record, excluding the first three fields. 
(That is, one half the number of total characters in the address, data, and 
checksum fields.) This field has two hexadecimal digits, representing a one-byte 
quantity. 


address . 

The address at which the data portion of the record is to reside in memory. 
The data goes to this address and successively higher numbered addresses. The 
length of this field is determined by the record type in the second byte of the S- 
record. 


data 

A variable length field containing the actual data to be loaded into memory. 
Specify each byte of data as a pair of hexadecimal digits in ASCII. 
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cksum 

A checksum compute over the length, address, and data fields. Compute 
the checksum as follows: 
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• add the values of the character pairs in the length, address, and data 
fields 

• take the one’s complement of the sum 

• drop the most significant byte 

Enter the least significant byte value in the checksum field as two ASCII 
hexadecimal digits. 

There are eight types of S-records. They can be divided into two categories: 
records containing actual data and records used to define and delimit groups of 
data-containing records. Types 1, 2, and 3 are reserved for records in the first 
category; types 0, 5, 7, 8, and 9 for reserved for records in the second category. 
Types 4 and 6 are not allowed. Table A-2 defines the types. 

Note: All byte values in Table A-2 are expressed as two ASCII characters 

representing the hexadecimal value. 

Table A-2. S-Record Type Definitions 


0 

This type is a header record used at the beginning of a group of S-records. 
The data field can contain any desired identifying information. The address field 
is two bytes long and is normally zero. 

1 

This type of record contains normal data. The address field is two bytes 

long. 

2 

This type is the same as type 1 except the address field is 3 bytes long. 

3 

This type is the same as type 1 except the address field is 4 bytes long. 

5 

This type indicates the number of type 1, 2, and 3 records in a group of S- 
records. The count is placed in the address field. The data field is empty. 

7 

This record signals the end of a block of type 3 S-records. If desired, the 4- 
byte address field can be used to contain an address at which to pass control. The 
data field is empty. 

8 

This type is the same as type 7 except that it ends a block of type 2 
S-records and the address field is 3 bytes long 
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9 

This is the same as type 7 except ending a block of type 1 S-records and the 
address field is 2 bytes long. 
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